Previous: Applying Customizations, Up: Customization [Contents][Index]
Custom themes are collections of settings that can be enabled or disabled as a unit. See Custom Themes in The GNU Emacs Manual. Each Custom theme is defined by an Emacs Lisp source file, which should follow the conventions described in this section. (Instead of writing a Custom theme by hand, you can also create one using a Customize-like interface; see Creating Custom Themes in The GNU Emacs Manual.)
A Custom theme file should be named
foo-theme.el, where foo is the
theme name. The first Lisp form in the file should be a call to
deftheme, and the last form should be a call to
provide-theme.
This macro declares theme (a symbol) as the
name of a Custom theme. The optional argument doc
should be a string describing the theme; this is the
description shown when the user invokes the
describe-theme command or types ? in
the ‘*Custom Themes*’ buffer.
Two special theme names are disallowed (using them causes
an error): user is a dummy theme that stores the
user’s direct customization settings, and
changed is a dummy theme that stores changes
made outside of the Customize system.
This macro declares that the theme named theme has been fully specified.
In between deftheme and
provide-theme are Lisp forms specifying the theme
settings: usually a call to
custom-theme-set-variables and/or a call to
custom-theme-set-faces.
This function specifies the Custom theme theme’s variable settings. theme should be a symbol. Each argument in args should be a list of the form
(var expression [now [request [comment]]])
where the list entries have the same meanings as in
custom-set-variables. See Applying
Customizations.
This function specifies the Custom theme theme’s face settings. theme should be a symbol. Each argument in args should be a list of the form
(face spec [now [comment]])
where the list entries have the same meanings as in
custom-set-faces. See Applying
Customizations.
In theory, a theme file can also contain other Lisp forms, which would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time.
The following functions are useful for programmatically enabling and disabling themes:
This function return a non-nil value if
theme (a symbol) is the name of a Custom theme
(i.e., a Custom theme which has been loaded into Emacs,
whether or not the theme is enabled). Otherwise, it returns
nil.
The value of this variable is a list of themes loaded into
Emacs. Each theme is represented by a Lisp symbol (the theme
name). The default value of this variable is a list
containing two dummy themes: (user changed). The
changed theme stores settings made before any
Custom themes are applied (e.g., variables set outside of
Customize). The user theme stores settings the
user has customized and saved. Any additional themes declared
with the deftheme macro are added to the front
of this list.
This function loads the Custom theme named
theme from its source file, looking for the source
file in the directories specified by the variable
custom-theme-load-path. See
Custom Themes in The GNU Emacs Manual. It
also enables the theme (unless the optional argument
no-enable is non-nil), causing its
variable and face settings to take effect. It prompts the
user for confirmation before loading the theme, unless the
optional argument no-confirm is
non-nil.
This function enables the Custom theme named theme. It signals an error if no such theme has been loaded.
This function disables the Custom theme named
theme. The theme remains loaded, so that a
subsequent call to enable-theme will re-enable
it.
Previous: Applying Customizations, Up: Customization [Contents][Index]